NAME¶

PAPI - Performance Application Programming Interface

SYNOPSIS¶

The PAPI Performance Application Programming Interface provides machine and operating system independent access to hardware performance counters found on most modern processors. Any of over 100 preset events can be counted through either a simple high level programming interface or a more complete low level interface from either C or Fortran. A list of the function calls in these interfaces is given below, with references to other pages for more complete details. For general information on the Fortran interface see: PAPIF(3)

Component PAPI¶

Beginning with version 3.9, PAPI supports extensions to count performance information on multiple simultaneous components. This capability is only provided in the low level interface. New or modified function calls are prefixed with an asterisk.

PAPI Presets¶

An extensive list of predefined events is implemented on all systems where they can be supported. For a list of these events, see: PAPI_presets(3)

PAPI Native Events¶

PAPI also supports interface functions for discovering the native events on a given platform. For more information on native events, see: PAPI_native(3)

High Level Functions¶

A simple interface for instrumenting end-user applications. Fully supported on both C and Fortran. See individual functions for details on usage.

PAPI_num_counters(3) - get the number of hardware counters available on the system
PAPI_flips(3) - simplified call to get Mflips/s (floating point instruction rate), real and processor time
PAPI_flops(3) - simplified call to get Mflops/s (floating point operation rate), real and processor time
PAPI_ipc(3) - gets instructions per cycle, real and processor time
PAPI_accum_counters(3) - add current counts to array and reset counters
PAPI_read_counters(3) - copy current counts to array and reset counters
PAPI_start_counters(3) - start counting hardware events
PAPI_stop_counters(3) - stop counters and return current counts

Note that the high-level interface is self-initializing. You can mix high and low level calls, but you must call either PAPI_library_init(3)orahighlevelroutinebefore calling a low level routine.

Low Level Functions¶

Advanced interface for all applications and performance tools. Some functions may be implemented only for C or Fortran. See individual functions for details on usage and support.

PAPI_accum(3) - accumulate and reset hardware events from an event set
PAPI_add_event(3) - add single PAPI preset or native hardware event to an event set
PAPI_add_events(3) - add array of PAPI preset or native hardware events to an event set
PAPI_assign_eventset_component(3)* - assign a component index to an existing but empty eventset
PAPI_attach(3) - attach specified event set to a specific process or thread id
PAPI_cleanup_eventset(3) - remove all PAPI events from an event set
PAPI_create_eventset(3) - create a new empty PAPI event set
PAPI_destroy_eventset(3) - deallocates memory associated with an empty PAPI event set
PAPI_detach(3) - detach specified event set from a previously specified process or thread id
PAPI_enum_event(3) - return the event code for the next available preset or natvie event
PAPI_event_code_to_name(3) - translate an integer PAPI event code into an ASCII PAPI preset or native name
PAPI_event_name_to_code(3) - translate an ASCII PAPI preset or native name into an integer PAPI event code
PAPI_get_component_info(3)* - get information about the component features
PAPI_get_dmem_info(3) - get dynamic memory usage information
PAPI_get_event_info(3) - get the name and descriptions for a given preset or native event code
PAPI_get_executable_info(3) - get the executable�s address space information
PAPIF_get_exe_info(3) - Fortran version of PAPI_get_executable_info with different calling semantics
PAPI_get_hardware_info(3) - get information about the system hardware
PAPI_get_multiplex(3) - get the multiplexing status of specified event set
PAPI_get_cmp_opt(3)* - query the component specific option settings of a specific event set
PAPI_get_opt(3) - query the option settings of the PAPI library or a specific event set
PAPIF_get_clockrate(3) - get the processor clockrate in MHz. Fortran only.
PAPIF_get_domain(3) - get the domain of the specified eventset. Fortran only.
PAPIF_get_granularity(3) - get the granularity of the specified eventset. Fortran only.
PAPIF_get_preload(3) - get the 'LD_PRELOAD' environment equivalent. Fortran only.
PAPI_get_real_cyc(3) - return the total number of cycles since some arbitrary starting point
PAPI_get_real_usec(3) - return the total number of microseconds since some arbitrary starting point
PAPI_get_shared_lib_info(3) - get information about the shared libraries used by the process
PAPI_get_thr_specific(3) - return a pointer to a thread specific stored data structure
PAPI_get_overflow_event_index(3) - decomposes an overflow_vector into an event index array
PAPI_get_virt_cyc(3) - return the process cycles since some arbitrary starting point
PAPI_get_virt_usec(3) - return the process microseconds since some arbitrary starting point
PAPI_is_initialized(3) - return the initialized state of the PAPI library
PAPI_library_init(3) - initialize the PAPI library
PAPI_list_events(3) - list the events that are members of an event set
PAPI_list_threads(3) - list the thread ids currently known to PAPI
PAPI_lock(3) - lock one of two PAPI internal user mutex variables
PAPI_multiplex_init(3) - initialize multiplex support in the PAPI library
PAPI_num_components(3)* - return the number of components currently installed
PAPI_num_cmp_hwctrs(3)* - return the number of hardware counters for a specified component
PAPI_num_hwctrs(3) - return the number of hardware counters for the cpu
PAPI_num_events(3) - return the number of events in an event set
PAPI_overflow(3) - set up an event set to begin registering overflows
PAPI_perror(3) - convert PAPI error codes to strings
PAPI_profil(3) - generate PC histogram data where hardware counter overflow occurs
PAPI_query_event(3) - query if a PAPI event exists
PAPI_read(3) - read hardware events from an event set with no reset
PAPI_register_thread(3) - inform PAPI of the existence of a new thread
PAPI_remove_event(3) - remove a hardware event from a PAPI event set
PAPI_remove_events(3) - remove an array of hardware events from a PAPI event set
PAPI_reset(3) - reset the hardware event counts in an event set
PAPI_set_debug(3) - set the current debug level for PAPI
PAPI_set_cmp_domain(3)* - set the component specific default execution domain for new event sets
PAPI_set_domain(3) - set the default execution domain for new event sets
PAPIF_set_event_domain(3) - set the execution domain for a specific event set. Fortran only.
PAPI_set_cmp_granularity(3)* - set the component specific default granularity for new event sets
PAPI_set_granularity(3) - set the default granularity for new event sets
PAPI_set_multiplex(3) - convert a standard event set to a multiplexed event set
PAPI_set_opt(3) - change the option settings of the PAPI library or a specific event set
PAPI_set_thr_specific(3) - save a pointer as a thread specific stored data structure
PAPI_shutdown(3) - finish using PAPI and free all related resources
PAPI_sprofil(3) - generate hardware counter profiles from multiple code regions
PAPI_start(3) - start counting hardware events in an event set
PAPI_state(3) - return the counting state of an event set
PAPI_stop(3) - stop counting hardware events in an event set and return current events
PAPI_strerror(3) - return a pointer to the error message corresponding to a specified error code
PAPI_thread_id(3) - get the thread identifier of the current thread
PAPI_thread_init(3) - initialize thread support in the PAPI library
PAPI_unlock(3) - unlock one of two PAPI internal user mutex variables
PAPI_unregister_thread(3) - inform PAPI that a previously registered thread is disappearing
PAPI_write(3) - write counter values into counters

PAPI Utility Commands¶

A collection of simple utility commands is available in the \utils directory. See individual utilities for details on usage.

papi_avail(1) - provides availability and detail information for PAPI preset events
papi_clockres(1) - provides availability and detail information for PAPI preset events
papi_cost(1) - provides availability and detail information for PAPI preset events
papi_command_line(1) - executes PAPI preset or native events from the command line
papi_decode(1) - decodes PAPI preset events into a csv format suitable for PAPI_encode_events
papi_event_chooser(1) - given a list of named events, lists other events that can be counted with them
papi_mem_info(1) - provides information on the memory architecture of the current processor
papi_native_avail(1) - provides detailed information for PAPI native events

SEE ALSO¶

The PAPI Web site: http://icl.cs.utk.edu/papi

PAPIF(3), PAPI_presets(3), PAPI_native(3)